Node / ReticulumProjects / MeshChatX.git / files / docs / en / architecture.md

Displaying Rendered • View raw • Download

MeshChatX is a heavily extended fork of Reticulum MeshChat. The goals below shaped how the codebase is organized.

• Keep a local-first runtime that works on desktop, mobile, containers, and single-board computers.

• Preserve Reticulum and LXMF semantics while improving usability and operational tooling.

• Support multiple identities in one process without cross-identity data leakage.

• Keep the Python backend and Vue frontend independently testable.

• Run in constrained environments with predictable SQLite behaviour.

Mesh features should follow Reticulum’s post-IP design patterns (portable identity hashes, announces, store-and-forward, transport-agnostic APIs, scarce payloads). Agent and contributor gates live in T383838docs/agents/conventions/reticulum-zen.md and T383838docs/agents/skills/reticulum-design-gates/SKILL.md, derived from the Zen of Reticulum.

One Python process owns the web server, Reticulum stack, and all per-identity managers. The Vue frontend is static assets served from T383838meshchatx/public/ after a Vite build.

T282828

Optional Electron wraps the same backend binary and loads the UI from the local HTTPS server.

T383838ReticulumMeshChat in T383838meshchatx/meshchat.py is the orchestration layer. It wires HTTP via T383838meshchatx/src/backend/http/, starts and stops identity contexts, wires crash recovery, and coordinates shared process concerns. Domain to route ownership is documented in T383838docs/agents/module-ownership.md.

Path helpers live in T383838meshchatx/src/path_utils.py, T383838ssl_self_signed.py, and T383838env_utils.py. T383838meshchat.py re-exports them for compatibility.

T383838IdentityContext in T383838meshchatx/src/backend/identity_context.py encapsulates everything tied to one cryptographic identity:

• Storage under T383838storage/identities/<identity_hash>/

• Identity-local SQLite database (schema version tracked in migrations)

• LXMF router state and propagation directories

• Manager instances for messages, announces, docs, maps, forwarding, bots, RRC, Nomad page nodes, and more

Switching identities tears down the old context and loads another. Global mutable state that could leak between identities is avoided by design.

Feature behaviour lives in modules under T383838meshchatx/src/backend/. Examples include message handling, announce trimming, documentation, maps, page nodes, telemetry, interfaces, forwarding aliases, and RN-specific tool handlers.

T383838meshchat.py should stay focused on transport and lifecycle. Business rules belong in managers where they can be unit tested.

• Engine: SQLite with explicit SQL and migrations (no ORM).

• Schema: Versioned migrations run during startup and identity setup.

• Backups: Automatic and manual database backups under T383838database-backups/.

• Recovery: T383838--auto-recover, emergency mode, and Electron crash UI can restore from backups.

Routes are registered through T383838backend/http/register.py into aiohttp route tables

(still discoverable as T383838@routes.<method> for contract scanners). Categories include:

• Application status and configuration

• Authentication and session management

• LXMF messaging and conversations

• Telephone and voicemail

• Interfaces and Reticulum configuration

• Nomad Network and page nodes

• RRC client and server

• Tools (ping, RNPath, RNCP, RNSH, translator, bots)

• Documentation and maintenance

The frontend uses T383838fetch via T383838apiClient.js with CSRF tokens on mutating requests.

The UI connects to T383838/ws for low-latency updates. Event types include new LXMF messages, identity switches, telephone state, RRC activity, Nomad download progress, RNCP transfers, and plugin events. Handlers are registered in T383838wsEventRegistry.js and dispatched through T383838wsEventBridge.js.

Audio calls can use T383838/ws/telephone/audio for browser-side codec bridging.

MeshChatX defaults toward secure local operation:

• HTTPS and WSS enabled by default.

• Self-signed certificates generated per identity when custom PEM files are absent.

• Optional HTTP basic authentication (T383838--auth).

• Encrypted session cookies via T383838aiohttp_session.

• CORS, CSP, and defensive middleware on HTTP responses.

• Access attempt logging with lockout when auth is enabled.

The project includes extensive automated tests around auth and sessions. Even so, exposing MeshChatX directly to the public internet is not recommended without additional hardening.

Password reset is available with T383838--reset-password or T383838MESHCHAT_RESET_PASSWORD=true, which clears the stored bcrypt hash so you can set a new password in the UI.

One source tree produces:

• Development runs via T383838uv run python -m meshchatx.meshchat

• Python wheels with bundled T383838public/ assets

• Container images (Alpine Dockerfile with standard/extra VARIANT, plus hardened Chainguard)

• Electron builds for Windows, macOS, and Linux

• Android APK via Chaquopy

Frontend build output always lands in T383838meshchatx/public/ so runtime behaviour matches across targets.

• Crash recovery integration in Electron and backend startup checks

• Database integrity verification

• Backup, restore, and snapshot APIs

• Explicit teardown when switching identities or shutting down forwarding resources

• Health and status endpoints suitable for container probes

MeshChatX supports plugins with separate frontend and backend runtimes:

• Contribution registries under T383838meshchatx/src/frontend/js/registries/ for navigation, tools, commands, settings, and WebSocket events.

• Frontend plugins run in dedicated Workers (T383838PluginHost.js) with declarative UI slots.

• Backend WASM plugins run in wasmtime with fuel metering and capability-gated host functions.

• Backend Python plugins (T383838backend.type: "python") run in-process with a permission-checked host (T383838log, managers, storage, network flag).

• WASM bundles embed manifest/files/signature in custom sections and unpack on install.

• Sideband-compatible loader optionally T383838execs flat T383838*.py plugins with T383838PLUGIN_COMMAND LXMF dispatch.

• Security core verifies RSG signatures, trusted publishers, integrity hashes, and heuristic findings.

• HTTP API under T383838/api/v1/plugins/* and T383838/api/v1/sideband-plugins/* for install, enable, invoke, trust, and Sideband config.

Practical extension paths today:

• Plugin manifests with T383838contributes and T383838permissions blocks

• New API routes and manager modules

• Frontend pages wired through registries

• New settings via T383838ConfigManager and CLI or environment variables

• Database schema changes through migrations

• Generic RNS Link transport over WebSocket (T383838rns.link.*) for external consoles and plugins (see RNS Link API)

Granted plugin manager capabilities include T383838destinationPath.read, T383838debugLog.read, T383838bugReport.*, and T383838rnsLink.open / T383838identify / T383838request / T383838send / T383838close. Hooks include T383838announce.received and T383838rns.link.event. Storage (T383838storage:isolated) and outbound HTTP (T383838network:fetch) are also grantable. The installation preview scans plugin files for external URLs and stores the user-selected grant subset.

When adding features, prefer identity-scoped state, explicit migrations, endpoint tests, and narrowly declared plugin permissions.

The Nomad browser and Mesh Server (page nodes) share a rendering pipeline for Micron, Markdown, plain text, and sanitised HTML. Authoring rules are documented in NomadNet page formats.

• Getting started for UI navigation and first steps.

• LXMF messaging, Audio calls, and Reticulum interfaces for feature behaviour.

• Plugins for extension architecture and security.

• The Reticulum tab in Documentation for protocol reference.